package com.google.code.jholidays.events;

import com.google.code.jholidays.core.EventDescriptor;

/**
 * Represents base interface for all event factories.
 * <p>
 * When custom plugin implements {@link IEvent} interface then corresponding
 * factory should be provided. For plugins management {@link IFactory}
 * implementation <b>must</b> provide no-argument constructor
 * <p>
 * For skeletal implementation see {@link AbstractFactory}
 * 
 * @author tillias
 * 
 */
public interface IFactory {

    /**
     * Creates new {@link IEvent} using given {@link EventDescriptor} and
     * possibly parent event.
     * <p>
     * If factory produces independent events (e.g. events having no parent
     * ones) pass null for <code>parent</code> parameter
     * 
     * @param descriptor
     *            Event descriptor which will be used to construct IEvent
     * @return Any subclass implementing {@link IEvent} interface
     */
    IEvent createEvent(EventDescriptor descriptor, IEvent parent);

    /**
     * Gets value indicating that factory can produce {@link IEvent} instance
     * using given descriptor
     * 
     * @param descriptor
     *            Event descriptor which will be checked against factory
     * @return True if factory can produce {@link IEvent} using given descriptor
     */
    boolean matches(EventDescriptor descriptor);
}
